Cream of the Crop 20

home *** CD-ROM | disk | FTP | other *** search

/ Cream of the Crop 20 / Cream of the Crop 20 (Terry Blount) (1996).iso / bbs / inf111.zip / INFOMAIL.DOC < prev next >

Wrap

Text File | 1996-06-29 | 65KB | 1,682 lines

Centurion InfoMail 1.11 A Document Server for Fidonet Systems Copyright (C) Damian Walker 1996 -*- Dedicated to the Memory of Trevor H. Walker InfoMail 1.11 CONTENTS 1. WHAT IS INFOMAIL 1.1. Program Description 1.2. System Requirements 1.3. Disclaimer 1.4. Acknowledgements 1.5. Version History 1.6. A Note for 386 Users 2. SETTING UP INFOMAIL 2.1. Global Parameters 2.1.1. Netmail Directory 2.1.2. InfoMail Name and Address 2.1.3. Header and Footer Files 2.1.4. Saving Your Setup 2.2. The Document List 2.2.1. Adding a document 2.2.2. Document Naming 2.2.3. The Access Counter 2.2.4. Document Flags 2.2.5. Document Subject and Message Status 2.2.6. Remote Maintenance Passwording 2.2.7. Document Filename 2.2.8. Saving the Document Record 2.2.9. Editing and Removing Documents 2.2.10. Saving the Document List 2.3. InfoMail Text Files 2.3.1. System Limits and Conventions 2.3.2. Using Macros in Text Files 2.4. Setting up InfoMail for Multiple Networks 2.5. Upgrading from a Previous Version of InfoMail 3. USING INFOMAIL 3.1. Running InfoMail on your Mailer 3.2. Requesting Documents from InfoMail 3.3. Remotely Updating Documents 3.4. The InfoMail Semaphore File 4. INFOMAIL REFERENCE 4.1. Command Line Format 4.2. Global Setup Fields 4.3. Document List Fields 4.4. InfoMail Text Macros 5. DEVELOPER'S GUIDE 5.1. The InfoMail File Formats 5.2. Supplied InfoMail Headers 5.3. Messages Generated by InfoMail 6. CONCLUSION Contents 2 InfoMail 1.11 1. WHAT IS INFOMAIL? Before attempting to install and use InfoMail, it could be advisable to find out what the program is about-- what it is intended to do, what it is not intended to do, what its requirements are, and what purposes it could be put to. 1.1. Program Description InfoMail is a document server for Fidonet systems. It scans your netmail directory for messages addressed to it, and performs some action based on those messages. Its basic function is to send out documents which the user has requested. A document is usually in the form of a text file, which can be sent in the body of a reply to the user who requested the document. A secondary function is to allow users to alter documents remotely, via netmail. This allows users who cannot run InfoMail themselves to have their own documents hosted at another system. There are many uses which InfoMail can be put to. It has been used to send out BBS information, echo descriptions and rules, reviews of games, FAQ documents and even a price list. The number of other uses which may be found for it are limited only by the imagination. **************************************************************** This program is in the public domain. This means that the program can be distributed and used, for an unlimited period, free of charge. If you find InfoMail useful, the author would be interested to hear from you. Your views on the program, and the uses you may find for it, are valuable sources of information. **************************************************************** Although the program name and code is protected by copyright, the author would be pleased to see similar programs appearing for the PC and other platforms. Should you as an author wish to write your own version of InfoMail, feel free to use the data structures, addressing methods and macros which InfoMail uses. Feel free also to use 'InfoMail' as the default name for your program to answer to. The author is more interested in InfoMail as a widespread idea than as a vehicle for personal fame and (!) fortune. 1.2. System Requirements InfoMail has been written to work on an IBM-compatible PC. The exact minimum requirements are not known, but there is no reason why this program should not work on anything from an 8088-based PC. The smallest machine it has been tested on is an 386sx/16 with 2mb RAM. Performance is adequate on that machine. What is InfoMail? 3 InfoMail 1.11 In order to be useful, InfoMail must be used with a Fidonet system which uses a *.MSG-style netmail directory. This includes FrontDoor, Terminate, and also static mailers such as BinkleyTerm and Xenia if these mailers are used with a mail processor supporting *.MSG message areas. InfoMail uses 80x25 text mode, in colour. It has also been tested with a true monochrome screen. It may be used in 80x50 mode, although the bottom half of the screen will not be cleared when using the setup editor and the document list editor. 1.3. Disclaimer **** IMPORTANT **** No warranty or guarantee is provided with this program. While the author has attempted to ensure that the program is fully operational and bug-free, no responsibilty can be taken by the author in the event that damage or inconvenience is caused by the program. Run InfoMail at your own risk. 1.4. Acknowledgements Thanks go to the following people for their help in the ongoing development of InfoMail: Bill Welch (2:254/222), for beta testing version 1.00. Bill Birrell (2:2504/200), for beta testing versions 1.00, 1.10 and 1.11, and for general programming help in the C echo. Steven Holme (2:2503/216), for beta testing versions 1.00 and 1.10, and for some useful suggestions. Jim O'Neill (2:256/68), for beta testing version 1.10. Martyn Wilkins (2:442/608), for promoting version 1.00 in echomail, and for beta testing versions 1.10 and 1.11. Peter Barley (2:2502/666.15), for beta testing versions 1.00 , 1.10 and 1.11, and for many useful suggestions. Andy Altoft (2:2502/666.2107), for beta testing versions 1.00 and 1.10. Peter Burnett (2:441/80), for some useful suggestions, and for beta testing version 1.11. Joaquim Homrighausen (2:270/17), for hatching versions 1.00 and 1.11 on SDSFRONT, thus attracting interest in the program from across the world. Kev Baillie (2:2502/1), for beta testing version 1.11, and for many useful suggestions for future releases of InfoMail. What is InfoMail? 4 InfoMail 1.11 1.5. Version History Version 1.00, original InfoMail, with the following features: - Alterable name and address - Universal kill flag for outgoing messages - 8-character document names - Posts documents up to 8k in size Version 1.10, first upgrade release, with these additions: - Global header and footer files for outgoing messages - 16-character document names - Document access counter - Macros for use in headers, footers and documents - Secret (unlisted) documents - Expanded subject line for outgoing messages - Optional kill and other message flags for each document - Remote maintenance of documents (passworded for security) - Posts documents up to 16k in size - Automatic upgrade facility - Increased speed of document posting - A couple of aesthetic minor interface bugs fixed - A 386 version of the program Version 1.11 - Document List display bug corrected - Some errors in the documentation were corrected 1.6. A Note for 386 Users InfoMail 1.10 came with a 386-specific executable file, INFO386.EXE. The performance gain for 386 users was not noticeable, so this file has been removed from the distribution archive for this version of InfoMail. What is InfoMail? 5 InfoMail 1.11 2. SETTING UP INFOMAIL Before setting up InfoMail, it is necessary to create a directory and extract the InfoMail archive into that directory. As you are reading this document, it will be assumed that you have managed to get that far without further help from this manual. If you are upgrading from InfoMail 1.00 to 1.11, then you might like to skip past the initial tutorial stage to section 2.5, which deals with the easy upgrade procedure. However, it is still advisable to read through the rest of this section in order to familiarise yourself with some of the new features of 1.11, and how to access them. If you are upgrading from InfoMail 1.10, then no upgrade is necessary as InfoMail 1.11 uses the same files. You can also dispense with the InfoList utility, as the bug it was designed to circumvent is not present in InfoMail 1.11. There are three parts to setting up InfoMail-- the global setup parameters, the document list, and the document text files themselves. This section of the manual will explore in tutorial form the various aspects of setting up a functional InfoMail system. It will make reference to example files provided with the InfoMail system. Feel free to follow it or not, as you please. 2.1. Global Parameters The first thing which needs to be set up in order for InfoMail to function is the set of global parameters. To set up InfoMail's global parameters type the following at the command prompt: INFOMAIL -S Capitalisation is unimportant in this, and all, aspects of InfoMail. After you have pressed <RETURN>, you should be presented with the InfoMail Setup Utility, which is centred upon a window like the following: ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ ▒╒═══════════════════════════════════════════════════════════╕▒▒ ▒│ Netmail .\ │░▒ ▒│ Name InfoMail │░▒ ▒│ Address 2:2502/666.0 │░▒ ▒│ Header │░▒ ▒│ Footer │░▒ ▒╘═══════════════════════════════════════════════════════════╛░▒ ▒▒░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░▒ ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ Setting Up InfoMail 6 InfoMail 1.11 As you load the setup utility for the first time, it creates the file INFOMAIL.CFG in your InfoMail directory, and writes to it the default settings shown in the window above. It is unlikely that these settings will be to your taste, unless you happen to take over the running of the author's node. The following subsections take you through altering these settings. 2.1.1. Netmail Directory The 'Netmail' field at the top of the window refers to the netmail directory. This is the directory in which your mailer or mail processor stores inbound and outbound *.MSG netmails. If you use a Hudson or Jam base to store netmail, you will have to change your software to use to *.MSG netmails before running InfoMail. When you start the setup editor, the Netmail field should be highlighted. Press <RETURN> when the field is highlighted to change the netmail directory. When you have finished editing your netmail directory, InfoMail will capitalise it and add a trailing backslash if one is not already present. 2.1.2. InfoMail Name and Address It is possible to change the name that InfoMail answers to. Using default settings, users address InfoMail at your system with the name 'InfoMail' as the 'Name' field shows. If you change this to 'Info', then users will have to address it as 'Info' instead of 'InfoMail'. It is recommended that you leave the Name field as 'InfoMail' in order to standardise the use of InfoMail from the users' point of view. Whatever the Name field says, InfoMail will always write its replies from 'InfoMail 1.11'. If you do wish to change this field, select the field name using the cursor keys, and press <RETURN> when 'Name' is highlighted. It is far more likely that you will wish to change the 'Address' field, and this course of action is highly recommended. To change the address field, highlight the 'Address' field name using the cursor keys, and press <RETURN>. Here you should enter your point or node address. If you are running a node, it could be desirable to designate a point address which InfoMail could use, for both aesthetic and technical reasons. When you have entered your point or node address, InfoMail will add a '.0' (if necessary). Setting Up InfoMail 7 InfoMail 1.11 2.1.3. Header and Footer Files A feature introduced into InfoMail 1.10 allows you to add a standard header and footer to all documents which InfoMail sends out from your system. These could contain your system name, some brief advertisement, or perhaps technical information about the document or message being sent. To specify a header file, move the cursor to the 'Header' field and press <RETURN>. There is a sample header file supplied with InfoMail, with the filename HEADER.SAM. As an example, enter this the full path and file name of this file (only you know what directory you have installed InfoMail into). A similar process allows you to specify a footer file. Select the 'Footer' field, and press <RETURN>. There is a sample footer file provided, called FOOTER.SAM, which you might like to use for this example. Note that InfoMail does not check for the existence of these files. This allows you to specify the names of files you have yet to create, without having to endure any annoying error messages. Leaving the header and footer files blank allows you to forego the thrill of using headers and footers on your documents. If you specify a header file but no footer file, your documets will be posted with a header only. The effects of supplying a footer file without a header file are therefore quite predictable. 2.1.4. Saving Your Setup After making the changes mentioned so far, the main window of the setup utility should resemble the following: ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ ▒╒═══════════════════════════════════════════════════════════╕▒▒ ▒│ Netmail C:\APPS\FD\MAIL\ │░▒ ▒│ Name InfoMail │░▒ ▒│ Address 2:2502/666.3 │░▒ ▒│ Header C:\UTILS\INFOMAIL\HEADER.SAM │░▒ ▒│ Footer C:\UTILS\INFOMAIL\FOOTER.SAM │░▒ ▒╘═══════════════════════════════════════════════════════════╛░▒ ▒▒░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░▒ ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ To save these parameters, press <ESC>. This will save a new INFOMAIL.CFG file with the above values, and return you to the command prompt. Setting Up InfoMail 8 InfoMail 1.11 2.2. The Document List When global parameters have been entered and saved, your next task is to create a list of documents which users may request. This can be anything from one document to 32767. If you find this number insufficient then the author will be very interested to hear from you. Note that InfoMail will function with no documents defined in the document list, but without documents to send, InfoMail's usefulness is rather difficult to define. To run the document list maintenance utility, type in the following on the command line: INFOMAIL -L When you have pressed <RETURN>, you will be presented with the InfoMail Document Maintenance utility, of which the central window resembles the following: ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ ▒╒═══════════════════════════════════════════════════════════╕▒▒ ▒│ X Document Subject │▒▒ ▒│ │░▒ ▒│ │░▒ ▒│ │░▒ ▒│ │░▒ ▒│ │░▒ ▒│ │░▒ ▒│ │░▒ ▒│ │░▒ ▒│ │░▒ ▒│ │░▒ ▒╘═══════════════════════════════════════════════════════════╛░▒ ▒▒░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░▒ ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ As you load the document maintenance utility for the first time, it will create an empty document list under the name of INFOMAIL.DAT. 2.2.1. Adding a Document A document may be added by pressing <RETURN> when the blank entry at the end of the list is highlighted. At the moment, the blank entry is the only entry in the list. Select it and press <RETURN>. When you have done this the screen should change, and resemble the following: Setting Up InfoMail 9 InfoMail 1.11 ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ ▒╒═══════════════════════════════════════════════════════════╕▒▒ ▒│ Document Accessed: 0 │▒▒ ▒│ Macros? Yes │░▒ ▒│ Listed? Yes │░▒ ▒│ Subject │░▒ ▒│ Status Kill │░▒ ▒│ Password │░▒ ▒│ File │░▒ ▒╘═══════════════════════════════════════════════════════════╛░▒ ▒▒░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░▒ ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ This is a single (blank) document record. You can edit the various fields by moving up and down using the cursor keys and pressing <RETURN> on any field you wish to edit. An example file called DOCUMENT.SAM is present in the distribution archive of InfoMail, and the following sections deal with this file as an example. 2.2.2. Document Naming The field which is highlighted as you first edit the document record is 'Document', which is the document name. This is the name by which users will request the document, so it is reasonably important that this field is just as you want it. Changing this field later on may cause confusion as users continue to request the old document name. To edit the document name, press <RETURN> when the 'Document' field label is highlighted. The document name may be of up to 16 characters, upper or lower case. Case is not too important, as document requests are case insensitive. It is not a good idea to include spaces in a document name, as this may interfere with other features described later. For the purposes of this example, name the document 'Sample'. 2.2.3. The Access Counter This field shows how many times the document has been accessed, and when adding a new document it should show 0. It is of more use when editing a document. Pressing <RETURN> on this field will reset the counter to 0. 2.2.4. Document Flags There are two document flags, Macros and Listed. Macros determines whether macros are to be used in the current document. Macros, described more fully later on, use the brace symbols { and }, and the option to turn macros off has been provided for those instances where documents are automatically generated and contain the braces as part of normal text. Setting Up InfoMail 10 InfoMail 1.11 Listed determines whether this document name will appear when a document list is sent out to users. Setting this to 'No' will hide the document. This is useful in allowing selective access to documents. Either of these fields may be flipped from 'Yes' to 'No' and vice versa, simply by selecting the field label with the cursor keys, and pressing <RETURN>. Since the sample document contains macros, and we want it to be listed, make sure that both fields contain 'Yes' for this example. 2.2.5. Document Subject and Message Status The 'Subject' field is the subject line which is put in the message header whenever this document is posted to a user. This could simply be the document name, or it could be something a little more descriptive. For this example, we want the subject line to be 'A Sample Document'. Edit the field by selecting 'Subject', pressing <RETURN>, and typing in the desired subject name. Status is the status of outgoing messages for this document. The available message flags are Kill, Crash, File (attach), FReq (file request), Hold and Update (request). To edit the message status, select status and press <RETURN>. Each of the flags may be toggled on or off by pressing its intial letter, apart from the case of FReq where the key is 'R'. For the purposes of the sample document, the default flag setting of 'Kill' should be sufficient. You might like to try other flag settings just to familiarise yourself with the procedure of setting message flags. When using File, FReq and Update, the message subject is used as a filename, just like the normal Fidonet standard. If you wanted InfoMail to return a binary file with a document via crash mail, example settings for Status and Subject would be as follows: Subject: C:\UTILS\INFOMAIL\NETINFO.ZIP Status: Crash File Kill This would crash the file NETINFO.ZIP to anyone requesting the document. Bear in mind that InfoMail has no control over when crash messages are sent, or which messages are sent crash. It is a good idea to make sure that you have full control over when and where crashmail messages are sent, using your mailer's facilities, if you are to use the Crash flag with InfoMail. For example, if you have placed no time restrictions on crashmail messages then you will want to make sure your mailer will not crashmail non-CM nodes. Setting Up InfoMail 11 InfoMail 1.11 2.2.6. Remote Maintenance Passwording InfoMail contains a feature called remote maintenance. This allows people who cannot run InfoMail on their own systems to automatically maintain a document at a host system. All that the host system's sysop needs to do is set the document up in the first place, and assign a password. The password is set using the 'Password' field on the document record screen. To enter a password, select 'Password' and type in the password, which may be up to 8 characters long. Leaving the password blank disables remote maintenance for this document. As we don't want DOCUMENT.SAM to be altered by users remotely, you can leave the Password field blank for this example. 2.2.7. Document Filename The last thing you need to tell InfoMail about the document is the filename of the text file you want it to send, ie. the text document itself. You can do this by selecting the 'File' field label and pressing <RETURN>. This allows you to enter a filename. When you have finished editing the filename, pressing <RETURN> causes InfoMail to accept and capitalise the filename. It is a good idea to include the full pathname to the file if you won't be running InfoMail from its own directory, or if the document file itself resides in another directory. It is not essential that the file exists at this point. You may create the document record before creating the document itself, without having to wade through annoying error messages from InfoMail. For this example the filename is DOCUMENT.SAM. Only you know what directory you have installed InfoMail to, and InfoMail does not verify the file at this stage, so make sure you have the pathname entered correctly. 2.2.8. Saving the Document Record At this stage, the document record window should look something like the following: Setting Up InfoMail 12 InfoMail 1.11 ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ ▒╒═══════════════════════════════════════════════════════════╕▒▒ ▒│ Document Sample Accessed: 0 │▒▒ ▒│ Macros? Yes │░▒ ▒│ Listed? Yes │░▒ ▒│ Subject A Sample Document │░▒ ▒│ Status Kill │░▒ ▒│ Password │░▒ ▒│ File C:\UTILS\INFOMAIL\DOCUMENT.SAM │░▒ ▒╘═══════════════════════════════════════════════════════════╛░▒ ▒▒░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░▒ ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ To save the document record, just press ESC. You will be returned to the previous window containing a list of documents, and to this list will now be added 'Sample'. To familiarise yourself with the process of adding documents, it may be advisable to try adding another one. There is only one sample provided, so for the second document you will have to search your imagination for ideas. This gives you a free hand to experiment with all the features of the document record editor. Once you have created and saved a second document record, the document list should look like this: ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ ▒╒═══════════════════════════════════════════════════════════╕▒▒ ▒│ X Document Subject │▒▒ ▒│ Sample A Sample Document │░▒ ▒│ MyDocument Some subject line or other │░▒ ▒│ │░▒ ▒│ │░▒ ▒│ │░▒ ▒│ │░▒ ▒│ │░▒ ▒│ │░▒ ▒│ │░▒ ▒│ │░▒ ▒╘═══════════════════════════════════════════════════════════╛░▒ ▒▒░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░▒ ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ 2.2.9. Editing and Removing Documents To edit a document, simply select its entry in the list and press <RETURN>. Any part of the document record may be altered, including the document name. To remove a document, select its entry and press <DELETE>. An asterisk (*) character will be placed under the X column header (X is the closest way that could be come up with of representing 'Delete' in a single character). Setting Up InfoMail 13 InfoMail 1.11 If you accidentally delete a document, you can 'undelete' it by pressing <DELETE> again when its entry is highlighted. In this way, <DELETE> acts as a toggle. Records are permanently removed when you exit the document list maintenance utility. 2.2.10. Saving the Document List The heading of this section is not a good one, as all changes are already saved by the time you want to exit the utility, save for the fact that 'deleted' records are still present. To exit the maintenance utility, press <ESC>. At this point, all the 'deleted' records will be removed permanently. 2.3. InfoMail Text Files The document files which InfoMail posts are simple text files on your system. This allows documents to be created in your favourite familiar text editor or wordprocessor. It also allows InfoMail to host documents which are automatically generated by other utilities, such as game score files and top user lists. Documents may be in any directory you like, as InfoMail allows the files to be referred to by their full pathname. 2.3.1. System limits and Conventions InfoMail text documents and outgoing netmails are limited to 16k in length. This is partly because some mail-processing utilities are limited to messages of this length, and it is partly to discourage the sending of huge text files via routed netmail. If a document you wish to host is longer than 16k, you might like to consider offering it as a FREQ, or if routed access is imperative, splitting it up into smaller text files. InfoMail header and footer files are limited to 1k in length. This was a programming constraint, and if there is demand, it may be changed in future versions of InfoMail. Since headers and footers are typically only a couple of lines in length, it is unlikely that a 1k restriction should cause a problem. A convention for InfoMail text files arises from a peculiarity of Fidonet netmail. A paragraph in a netmail message is stored as a continuous line of text. Message editors reformat these paragraphs 'on the fly', preventing netmails from looking 'ugly' where the screen width of the recipient differs from that of the sender. Setting Up InfoMail 14 InfoMail 1.11 Because of this feature, you might like to consider putting paragraphs in InfoMail documents on a single line, instead of reformatting the paragraphs in your editor. This is particularly useful when you start to use Macros, which make the length of lines uncertain and can cause ugly reformatting of messages if you are not careful. The last thing to bear in mind when writing InfoMail documents is that any kludge lines found in messages will be masked by replacing the ^A symbol with an @ sign. This prevents InfoMail and other software from getting confused when technical information (such as message ID and originating system) finds its way into the document text file. 2.3.2. Using Macros in Text Files One important addition to InfoMail 1.10/1.11 is that of Macros. These are simple text codes which can be embedded in a document or in the standard header and footer files, which are expanded into meaningful information when InfoMail posts a document. Macros are useful because they represent information which can be different from one message to the next, so such information could not just be inserted into the document as normal text. Consider the sample file DOCUMENT.SAM: ================================================================ Hello {F}! This is the document '{D}' which you have requested from {I}, the {P} server at {A}. This document has been accessed {C} time(s). Other documents may be available at this system, contact the sysop for further details. ================================================================ Note that in the file itself, the text of the paragraph is all on one line, for reasons stated in the previous section. If the user Damian Walker at 2:2502/666.0 requested this document from your system, the following message would be returned: ================================================================ By: InfoMail 1.11, 1:234/567.8 To: Damian Walker, 2:2502/666.0 Re: A Sample Document St: Kill ---------------------------------------------------------------- Hello Damian! This is the document 'Sample' which you have requested from InfoMail, the InfoMail 1.11 server at 1:234/567.8. This document has been accessed 2 time(s). Other documents may be available at this system, contact the sysop for further details. ================================================================ Setting Up InfoMail 15 InfoMail 1.11 If you have set up header and footer files, these will appear at the top and bottom of the message text. Macros can be used in these headers and footers just as they can in the message text, but note that if a document has 'Macros?' set to 'No', these macros will not be expanded. A full list of available macros is given in the InfoMail Reference section. 2.4. Setting up InfoMail for Multiple Networks At present, InfoMail has no AKA feature. However, using other features of InfoMail you can indirectly emulate the AKA feature in a more versatile manner than a simple feature of entering multiple addresses in the setup utility. The key feature is the -P switch, which tells InfoMail where its data files are stored. Consider the following directory tree: UTILS └─INFOMAIL ├─FIDONET ├─TREKNET └─MERCURY This assumes, for example purposes, that you have a presence (node or point) in the Fidonet, Treknet and Mercurynet networks. The \UTILS\INFOMAIL directory would contain INFOMAIL.EXE, INFOMAIL.DOC and all the documents common to all three networks. The FIDONET, TREKNET and MERCURY directories would contain an INFOMAIL.CFG and an INFOMAIL.DAT, along with any documents specific to those networks. By using the -P switch, you could run InfoMail using information in each of these directories. The INFOMAIL.CFG file in each directory would have the AKA for that network as its InfoMail Address, and could have possibly varying header and footer files, customised for that particular network. The INFOMAIL.DAT file could have entries pointing to common documents (ie. they would be identical in each file), as well as documents only accessible to those in each particular network. It is easy to see how this method of implementing AKA's is much more powerful than a simple list of addresses in the global setup parameters. 2.5. Upgrading from a Previous Version of InfoMail This section is only of interest to people running versions 1.00 and 1.10 of InfoMail, who want a quick and easy, no-fuss upgrade procedure. In order to upgrade InfoMail 1.00 files for use with InfoMail 1.11, just use the following command line: Setting Up InfoMail 16 InfoMail 1.11 INFOMAIL -U while in the InfoMail directory. This will convert both the .CFG and the .DAT file to the new standard. This is necessary in order to run InfoMail with your old setup. This option is a quick-and-dirty upgrade. It does not use any of the new features of InfoMail, it just allows you to use InfoMail 1.11 in the same way as you were using 1.00. It is useful for sysops who are pushed for time, and wish to delay taking advantage of new features until later. It is also handy for sysops with a large number of documents, as it removes the need for the sysop to re-enter the details of these documents. There are a few things you may wish to know about the 1.00->1.10 upgrade process, and how it upgrades the files with regard to new features: Header and Footer files are not specified; the fields are blank. This means that headers and footers will not automatically be added until you say so. The value of the universal Kill flag of version 1.00 will be used in determining the status of outgoing messages for each document. If Kill is set to Yes, then the Kill flag will be set for each document. Macros will be set to No for all documents, in case those documents contain brace {} characters. If you wish to use a macro in your header or footer, you must change the Macros field to Yes in all your documents (and ensure the documents don't contain brace characters as part of their normal text). Listed will be set to Yes for all documents, so that InfoMail 1.11 will list them all as 1.00 did. The Subject will be a copy of the document name at first. This also makes version 1.11 act just like 1.00. It will be desirable to change at least some of these as early as possible. You may like to change some document names to take advantage of the new 16-character limit, you may like to set Macros to Yes, and set a more descriptive subject line for your documents. If you wish to upgrade from InfoMail 1.10 to InfoMail 1.11, then it is not necessary to run the upgrade utility; 1.10 and 1.11 use the same file format. Setting Up InfoMail 17 InfoMail 1.11 If you are using InfoList, the temporary bug fix program for InfoMail 1.10, you may delete it once you have successfully installed InfoMail 1.11. InfoList will still work with 1.11, so if you have used it in batch files or elsewhere in your setup, you can leave everything as it is and make the changes at your convenience. Setting Up InfoMail 18 InfoMail 1.11 3. USING INFOMAIL Now that you have InfoMail set up, you will want to make proper use of the utility, and that is what this section is all about. If you wish to experiment with InfoMail, it may be a good idea to have handy a message editor capable of writing netmails to the directory you specified in the setup utility. 3.1. Running InfoMail on your Mailer It is your choice exactly how you run InfoMail. At one extreme, you may run it on an occasional basis, whenever you see a document request come in. You could run InfoMail in your daily maintenance, posting off documents once per day before or after you call your NC or hub. Or at the other extreme, you could run InfoMail after each mail call (as the author does). If you are a point, you could run InfoMail directly before or after you have polled your boss for your mail. Running InfoMail after polling your boss allows you to see the messages InfoMail creates. Running InfoMail before you poll your boss allows you to see the incoming messages to InfoMail. These are often a source of amusement, as people write their requests under the impression that no human eyes will see them. Which ever way you do this, the process is simple. At its simplest, you make sure you are present in the InfoMail directory and run the following command line: INFOMAIL This reads the setup and document list files from the current directory, scans your netmail directory for document requests and posts replies. If you wish to run InfoMail from another directory (which is likely if you are running a node), then you must use the -P switch, as follows: INFOMAIL -PC:\UTILS\INFOMAIL\ The trailing backslash is optional, InfoMail adds it internally if it is not already present. Alternatively, InfoMail has its own environment variable which you may use if the method shown above is not to your taste. At any time before you run InfoMail, you can type the following at the command line: SET INFOMAIL=C:\UTILS\INFOMAIL\ Substitute for C:\UTILS\INFOMAIL\ the directory in which you have installed InfoMail. As with the -P switch, the trailing backslash is optional. Using InfoMail 19 InfoMail 1.11 As InfoMail is running, you see a brief commentary on what it is doing. When scanning netmail, the message 'Scanning netmail...' and a little rotating bar made of ASCII characters shows that InfoMail is busy. When a request is found, InfoMail will print this information on the screen as well. InfoMail stores details of all its activities into an ASCII log file, called INFOMAIL.LOG, located in InfoMail's own directory. It is advisable to check this file every once in a while, especially when first setting up InfoMail, as it can help to track down errors caused by incorrectly setting up the program. 3.2. Requesting Documents from InfoMail It is easy for users to request documents from InfoMail. In our examples from section 2, the document 'Sample' was set up to send DOCUMENT.SAM. If you wish to try out these examples with your message editor, make sure you have this document set up correctly in the document list editor. To request sample from your system, a user would post the following message: ================================================================ By: A User, 2:345/678.9 To: InfoMail, 1:234/567.8 <assumes these settings in setup> Re: Sample ---------------------------------------------------------------- Message body ignored. ================================================================ As the message says, the message body is ignored by InfoMail. It is a good idea to put something in the message body, as some mail processors delete empty messages. This could happen anywhere along the netmail's route. When this message has arrived at your system (assumed to be 1:234/567.8 in this example), and InfoMail is run, the message will be deleted and InfoMail will send out a reply containing the document 'Sample', complete with macros expanded. The subject and status of the returned message is as set up in the document list maintenance utility. If a user writes to InfoMail requesting a document which does not exist, a polite message is sent back to them telling them of their error, and showing a list of documents which they can request from your system. 3.3. Remotely Updating Documents In order to experiment with this feature, it may be a good idea to set up an updatable document in the document list maintenance utility, ie. a document with an update password. This section of the manual will assume you have set the document up with the name 'UpdateMe', and the password 'Secret'. Using InfoMail 20 InfoMail 1.11 The user addresses a netmail to whatever you have called InfoMail at your system (in the setup utility), with the word UPDATE added on. For example, if you left your system to answer to the name of InfoMail, the user would address a netmail to InfoMail UPDATE. The subject line of the user's message would contain the document name, a space, and the password. This is the reason why document names should not contain spaces. So, for our example, the message would be as follows: ================================================================ By: A User, 2:345/678.9 To: InfoMail UPDATE, 1:234/567.8 Re: UpdateMe Secret ---------------------------------------------------------------- These are the updated document contents. ================================================================ As you can see, the message body contains the updated document contents. The body of the message as is will be taken as the new document. This process actually overwrites the existing text file, so it is a good idea to leave the password blank on any document which you do not want to be updated by other users, and to make sure that the only users who know a document's password are those who you want to update the document. These updated documents may contain macros, which will be stored in the text file and expanded whenever the document is posted (just like InfoMail documents which you maintain yourself). 3.4. The InfoMail Semaphore File If you are worried about using InfoMail under a multitasking or multiline system, then there is no need to be concerned. With InfoMail 1.10/1.11 there has been added a semaphore file, which the program creates when it is fired up and deletes when it has finished. InfoMail will not run if this file is already present in the InfoMail directory. This means that if InfoMail is running in one DOS session and you (or your node's batch file) tries to start it up in another DOS session, InfoMail will not load a second time. This prevents sharing violation errors which were a problem with earlier versions of InfoMail (not spotted as the author's system is not multiline). The file InfoMail checks for and creates is INFOMAIL.SEM, and this is a simple empty file. If it amuses you, you can easily confuse InfoMail by creating the INFOMAIL.SEM file yourself, in which case InfoMail will refuse to run unless you delete it. Using InfoMail 21 InfoMail 1.11 4. INFOMAIL REFERENCE This section of the manual contains a more comprehensive version of the information already covered, in a form which makes it easy for later reference. 4.1. Command Line Format INFOMAIL [-Ppath] [ <-S|-L|-U|-?> ] or INFO386 [-Ppath] [ <-S|-L|-U|-?> ] -Ppath specifies the directory in which InfoMail will find its INFOMAIL.CFG and INFOMAIL.DAT files (ie. the global setup and the document list file). -S enters the setup utility. -L enters the document list maintenance utility. -U upgrades an existing InfoMail 1.00 installation to InfoMail 1.11. A simple file length check is made to ensure that you do not run this after you have already upgraded InfoMail. -? requests a simple help screen which contains this information. All swiches may be specified with a DOS-style slash (?) instead of a hyphen (-). In addition, the path in the -P switch may contain DOS backslashes (\) or Unix/Amiga slashes (/). All switches may be in upper or lower case. The -P or /P option must have a space following the filename, if it is followed by one of the other options. The other options do not need a space if you are using DOS-style slashes for them. So the following are legal command lines for invoking InfoMail: INFOMAIL /S/Pc:\utils\infomail INFOMAIL -s -pc:/utils/infomail INFOMAIL /Pc:/utils/infomail /S whereas the following are not legal: INFOMAIL /Pc:\utils\infomail/S INFOMAIL /Pc:/utils/infomail/S 4.2. Global Setup Fields Netmail: This is the directory in which your system stores its *.MSG netmails. Either DOS or Unix style directory separators may be used. If no slash or backslash is added to the end of this name, InfoMail will add a DOS-style backslash. InfoMail Reference 22 InfoMail 1.11 Name: This is the name InfoMail will respond to. Unlike version 1.00, InfoMail 1.10/1.11 will not post its replies from this name, but will use the name InfoMail 1.11 instead. Address: This is the address of your system, or an alternative AKA you wish InfoMail requests to be addressed to. If no point number is used, .0 will be added by InfoMail. Header: This is the full path and filename of your standard header file (text to be posted at the top of every outgoing document). If left blank, no header will be used. It may contain DOS or Unix style directory separators. Footer: This is the full path and filename of your standard footer file (text to be posted at the bottom of everyo outgoing document). If left blank, no footer will be used. It may contain DOS or Unix style directory separators. 4.3. Document List Fields Document: The document name, up to 16 characters in length. This is the name which users will place on the subject line to request or update the document. Accessed: This is the access counter, showing how many times a document has been accessed (requested or updated). It may be embedded in documents, headers and footers as a macro. It may be reset to 0, but no other value may be placed in this field. Macros?: A flag to say whether macros will be expanded in this document or not. Set to 'No' in order to prevent confusion when documents contain braces {} as part of their ordinary text. Listed?: A flag to say whether the document will be listed in a document list. This is useful for creating 'secret' documents, and in effect the document name of a non-listed document acts as its password. Subject: The subject line of outgoing messages which contain this document in the message body. May be used as a file name in conjunction with certain message status flags. Status: The outgoing message status. Flags which may be set are Crash, Hold, Kill, File, FReq, Update. When File, FReq or Update is used, the subject acts as a filename. File: The full path and filename of the document text file. 4.4. InfoMail Text Macros {A} - The address of this system as defined in the setup utility, eg. '2:2502/666.0' InfoMail Reference 23 InfoMail 1.11 {C} - The access counter, eg. '3'. {D} - The tag name of this document, eg. 'Sample'. {F} - The first name of the user who has requested this document, eg. 'Damian' {I} - The name which InfoMail answers to at this system, eg. 'InfoMail'. {L} - The last name of the user who has requested this document, eg. 'Walker' {N} - The full name of the user who has requested this document, eg. 'Damian Walker' {P} - The full program name and version, in this version, 'InfoMail 1.11'. {S} - The subject line for this document, eg. 'A Sample Document'. {U} - The Fidonet address of the user who has requested this document, eg. '2:345/678.9'. Each macro can contain a numeric length specifier within the braces, which expands macros to this minimum length, for example, {C5} for a 5-character access counter or {D16} for a 16-character document name. The length specifier can occur before or after the macro letter, eg. {16D} instead of {D16}. If you really want to be perverse, you could even use {1D6}, though it is not guaranteed that this will always be the case in future versions. InfoMail Reference 24 InfoMail 1.11 5. DEVELOPER'S GUIDE This developer's guide allows other software authors to write additional utilities to service InfoMail, or to allow InfoMail to function as an integral part of some larger package. Examples which spring to mind are programs which may automatically sort, edit or add to the document list. 5.1. The InfoMail File Formats There are two files which you will need to know about for InfoMail, and these are INFOMAIL.CFG and INFOMAIL.DAT. INFOMAIL.CFG This is the file modified by the setup utility. It consists of a single header record and a single configuration record, built up as follows: Header Record This is an 8-character record which should contain the text INF110S<NUL> where <NUL> is the ASCII value zero. If this header is not present, InfoMail will assume that an invalid setup file, or no setup file, is present, and will create a new setup file in its place. Configuration Record This contains a number of fields, for which the programming aspects are described below. The purpose of these fields is discussed from a user's perspective in section 4.2. Netmail: This is a 64-character null-terminated string (or character array, if you like). It must contain a trailing backslash or slash if InfoMail is to function properly. InfoMail adds this when a user enters a new value, it does _not_ add the trailing backslash each time the netmail scan is run. Name: This is a 36-character null-terminated string. A lack of null termination on this or any stored InfoMail string will cause the program to do something silly. Address: A set of four 2-byte signed integers, representing zone, net, node and point of the Fidonet address. InfoMail internally groups these with the Name using the ftnuser structure described later on. Flags: This field is a 2-byte integer used in previous versions of InfoMail for a universal Kill flag; a non-zero value specified that outbound messages were to be killed when sent. Future versions of InfoMail may use this field for any global flags which may be needed. Developer's Guide InfoMail 1.11 Header/Footer: These are 64-character null-terminated strings. InfoMail capitalises these values before they are saved, so it is advisable that any other program does the same for aesthetic reasons. The validity of these fields is only checked by InfoMail (or more accurately, DOS) when attempting to open them. INFOMAIL.DAT This is the document list, which contains a single header record and an unlimited number of document records. InfoMail is limited to 32767 document records simply because the document number is held internally as a 2-byte signed integer. Header Record This is a simple 8-character string containing the value INF110D<NUL>, where <NUL> is the ASCII character 0. If the value of this field is different, InfoMail will assume an invalid or non-existent data file, and will attemp to create a new file in its place. Document Record This contains a number of autonomous and combined fields, described from a programmer's point of view below. A description of the use of these fields is given in section 4.2. Deleted: A 2-byte integer used internally by InfoMail to mark deleted records. As deleted records are removed by InfoMail upon exit of the document list utility, this field should always contain zero. Putting any other value here will cause documents to be shown as 'deleted' when the user enters the document list utility. Name: A null-terminated 17-character string, or character array. Lack of null termination will cause InfoMail to behave in a silly fashion. Flags: This is a 2-byte integer which serves as the Macros and Listed flags. Bit 0 (value 0/1) is the Macros flag, and bit 1 (value 0/2) is the Listed flag. The other bits are not currently used, but may be used in the future, so they ought to be set to 0. Subject: A simple 64-character null-terminated string. Attribute: A 2-byte status word in the format defined in the technical document FTS-1. This status flag is copied to the attribute field of all outgoing messages. InfoMail always sets the Pvt and Local flags in this field upon creating a new document record, but does not subsequently check them. For a full description of the attribute flags, refer to document FTS-1. Developer's Guide InfoMail 1.11 Password: A null-terminated 9-character string, allowing up to 8 characters to be used as a password. File: A null-terminated 64-character string. The existence of this file is not checked by InfoMail until it attempts to post it in response to a request. 5.2. Supplied InfoMail Headers A single header file is supplied in the InfoMail archive, and this is INFOMAIL.H. This contains the structures for the setup file and the document list file. 5.3. Messages Generated by InfoMail Messages generated by InfoMail are to the standard defined by FTS-1, and include the zone and point fields defined in the later versions of this document. InfoMail also includes the following kludge lines in the messages: ^APID The InfoMail 1.11 program ID ^AMSGID A random message ID ^AFMPT Set on messages generated from a point address ^ATOPT Set on messages send to a point address ^AINTL Generated on all messages Developer's Guide InfoMail 1.11 6. CONCLUSION It is hoped that you will find InfoMail useful. As mentioned earlier in the document, if you find the program useful, the author would appreciate a netmail from you, saying what you think of the program, and what uses you have found for it. Suggestions for improvement are also welcome; indeed, several of the improvements built into InfoMail 1.10/1.11 have been things which the author would not have thought to include himself. Version 1.00 has attracted interest around the world, despite the fact that other document servers had already been written. The improvements in version 1.10 attracted more people to this easy way of distributing information to interested parties, and hopefully this bug fix release will solve any problems experienced by users of InfoMail 1.10. Although I cannot guarantee that a future version of InfoMail will be released, your ideas for new features will be welcome. Enjoy! Damian Walker, Centurion (2:2502/666), June 1996. Conclusion 28